<html>
    <head>
        <style>
            body {
              max-width: 600px;
              margin: 50px auto;
              font-family: Arial;
              font-size: 15px;
              line-height: 1.5em;
            }
            .tip {
              font-size: .8em;
            }
        </style>
    </head>
    <body>

<h1>Halo UI plugin</h1>

<p>Halo UI plugin creates a control panel above an element.</p>

<h2>Install</h2>

<p>Add <code>joint.ui.halo.css</code> and <code>joint.ui.halo.js</code> files to your HTML:<p>
<pre><code>
&lt;link rel="stylesheet" type="text/css" href="joint.ui.halo.css" /&gt;
&lt;script src="joint.ui.halo.js"&gt;&lt;/script&gt;
</code></pre>

<h2>Create a halo</h2>

<pre><code>
var graph = new joint.dia.Graph;
var paper = new joint.dia.Paper({

    el: $('#paper'),
    width: 500,
    height: 500,
    gridSize: 1,
    model: graph
});

paper.on('cell:pointerup', function(cellView) {

    // We don't want a Halo for links.
    if (cellView.model instanceof joint.dia.Link) return;   

    var halo = new joint.ui.Halo({

        graph: graph,
        paper: paper,
        cellView: cellView
    });

    halo.render();
});
</code></pre>

<p>The <code>joint.ui.Halo</code> constructor takes a graph and paper objects + it also requires the view of a cell we want to display the halo above.</p>

<h2>Halo & magnets</h2>

<p>The Halo automatically detects an element's magnets and create unique link tools for each of them (see demo - model element). To control which link tools to be created use <code>magnetFilter</code> option. The value assigned could be a selector, a function (accepting magnet element as the first parameter), an element or a jquery object (see <a href="http://api.jquery.com/filter/">jQuery.filter</a> signature).</p>

<pre><code>
    var halo = new joint.ui.Halo({

        graph: graph,
        paper: paper,
        cellView: cellView,
        magnetFilter: function(magnetEl) { return $.contains(cellView.$('.inPorts')[0], magnetEl); }

    });
</code></pre>

<h2>Disabling halo tools</h2>

<p>Built-in functions are <code>remove</code>, <code>resize</code>, <code>rotate</code>, <code>clone</code>, <code>fork</code>, <code>link</code> and <code>unlink</code>. To revoke any of these functions you may add a line similar to the following to your css:</p>

<pre><code>
.halo .clone { display: none; } /* disables the clone tool */
</pre></code>

<h2>Customizing halo tools</h2>

<p>The best way to customize your halo is to inherit from the <code>joint.ui.Halo</code>. (Note that you can also edit the <code>joint.ui.Halo</code> class directly if you prefer to. Inheritance is recommended though as later updates to the Halo plugin might complicate your efforts.)</p>

<pre><code>
joint.ui.CustomHalo = joint.ui.Halo.extends({

    events: {
        'mousedown .custom': 'doSomething'
    },

    doSomething:  function(evt) {
        // something..
    }

});
</pre></code>

<p>Then you need to update the <code>halo.html</code> template and add your own tool there.
Once you have that, you can style your custom icon in <code>halo.css</code>. We suggest you to look at the default stylesheet for
the current Halo (<code>joint.ui.halo.css</code>) for reference on how to position your custom tool.
The last step is to run <code>grunt</code> in the Halo directory (where the Gruntfile.js file is located). Running grunt makes sure
your template gets compiled. After this step, all the files you need can be found in the <code>dist</code> directory.</p>

<h3>Grunt build file prerequisities</h3>

<p><a href="http://gruntjs.com/">Grunt</a> is a JavaScript Task Runner. JointJS uses it extensively in the build process. Follow the next
paragraph to be able to use Grunt for compiling a Halo template.</p>

<p>First, you need to have <a href="http://nodejs.org">NodeJS</a> and <a href="https://github.com/gruntjs/grunt-cli">grunt-cli</a>
installed. Once you have these, you need to install all the dependencies of the <code>Gruntfile.js</code> build file. This
can be done with one command: <code>npm install</code> in the <code>Halo</code> directory (where the <code>package.json</code> file is located). After that
you can just run <code>grunt</code> as described in the paragraph above.</p>

<h3>Using your custom Halo</h3>

<p>The use of custom halo tools is equivalent to the default halo tools. The only difference is that you instantiate your
halo using your newly created constructor:</p>

<pre><code>
paper.on('cell:pointerup', function(cellView) {

    // We don't want a Halo for links.
    if (cellView.model instanceof joint.dia.Link) return;

    var halo = new joint.ui.CustomHalo({

        graph: graph,
        paper: paper,
        cellView: cellView
    });

    halo.render();
});
</pre></code>
